home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / print / gs261ini.zip / DRIVERS.DOC < prev    next >
Text File  |  1993-05-26  |  29KB  |  679 lines
  1.    Copyright (C) 1989, 1990, 1991, 1992, 1993 Aladdin Enterprises.
  2.      All rights reserved.
  3.  
  4. This file is part of Ghostscript.
  5.  
  6. Ghostscript is distributed in the hope that it will be useful, but
  7. WITHOUT ANY WARRANTY.  No author or distributor accepts responsibility
  8. to anyone for the consequences of using it or for whether it serves any
  9. particular purpose or works at all, unless he says so in writing.  Refer
  10. to the Ghostscript General Public License for full details.
  11.  
  12. Everyone is granted permission to copy, modify and redistribute
  13. Ghostscript, but only under the conditions described in the Ghostscript
  14. General Public License.  A copy of this license is supposed to have been
  15. given to you along with Ghostscript so you can know your rights and
  16. responsibilities.  It should be in a file named COPYING.  Among other
  17. things, the copyright notice and this notice must be preserved on all
  18. copies.
  19.  
  20. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  21.  
  22. This file, drivers.doc, describes the interface between Ghostscript and
  23. device drivers.
  24.  
  25. For an overview of Ghostscript and a list of the documentation files, see
  26. README.
  27.  
  28. ********
  29. ******** Adding a driver ********
  30. ********
  31.  
  32. To add a driver to Ghostscript, all you need to do is edit devs.mak in
  33. two places.  The first is the list of devices, in the section headed
  34.  
  35. # -------------------------------- Catalog ------------------------------- #
  36.  
  37. Pick a name for your device, say smurf, and add smurf to the list.
  38. (Device names must be 1 to 8 characters, consisting of only letters,
  39. digits, and underscores, of which the first character must be a letter.
  40. Case is significant: all current device names are lower case.)
  41. The second is the section headed
  42.  
  43. # ---------------------------- Device drivers ---------------------------- #
  44.  
  45. Suppose the files containing the smurf driver are called joe and fred.
  46. Then you should add the following lines:
  47.  
  48. # ------ The SMURF device ------ #
  49.  
  50. smurf_=joe.$(OBJ) fred.$(OBJ)
  51. smurf.dev: $(smurf_)
  52.     $(SHP)gssetdev smurf $(smurf_)
  53.  
  54. joe.$(OBJ): joe.c ...and whatever it depends on
  55.  
  56. fred.$(OBJ): fred.c ...and whatever it depends on
  57.  
  58. If the smurf driver also needs special libraries, e.g., a library named
  59. gorf, then the gssetdev line should look like
  60.     $(SHP)gssetdev smurf $(smurf_)
  61.     $(SHP)gsaddmod smurf -lib gorf
  62.  
  63. ********
  64. ******** Keeping things simple
  65. ********
  66.  
  67. If you want to add a simple device (specifically, a black-and-white
  68. printer), you probably don't need to read the rest of this document; just
  69. use the code in an existing driver as a guide.  The Epson and BubbleJet
  70. drivers (gdevepsn.c and gdevbj10.c) are good models for dot-matrix
  71. printers, which require presenting the data for many scan lines at once;
  72. the DeskJet/LaserJet drivers (gdevdjet.c) are good models for laser
  73. printers, which take a single scan line at a time but support data
  74. compression.  For color printers, the DeskJet 500 C driver (gdevcdj.c) is
  75. a good place to start.
  76.  
  77. On the other hand, if you're writing a driver for some more esoteric
  78. device, or want to do something like add new settable attributes (besides
  79. page size and resolution), you probably do need at least some of the
  80. information in the rest of this document.  It might be a good idea for you
  81. to read it in conjunction with one of the existing drivers.
  82.  
  83. ********
  84. ******** Driver structure ********
  85. ********
  86.  
  87. A device is represented by a structure divided into three parts:
  88.  
  89.     - procedures that are shared by all instances of each device;
  90.  
  91.     - parameters that are present in all devices but may be different
  92.       for each device or instance; and
  93.  
  94.     - device-specific parameters that may be different for each instance.
  95.  
  96. Normally, the procedure structure is defined and initialized at compile
  97. time.  A prototype of the parameter structure (including both generic and
  98. device-specific parameters) is defined and initialized at compile time,
  99. but is copied and filled in when an instance of the device is created.
  100.  
  101. The gx_device_common macro defines the common structure elements, with the
  102. intent that devices define and export a structure along the following
  103. lines:
  104.  
  105.     typedef struct smurf_device_s {
  106.         gx_device_common;
  107.         ... device-specific parameters ...
  108.     } smurf_device;
  109.     smurf_device gs_smurf_device = {
  110.         sizeof(smurf_device),        * params_size
  111.         { ... procedures ... },        * procs
  112.         ... generic parameter values ...
  113.         ... device-specific parameter values ...
  114.     };
  115.  
  116. The device structure instance *must* have the name gs_smurf_device, where
  117. smurf is the device name used in devs.mak.
  118.  
  119. All the device procedures are called with the device as the first
  120. argument.  Since each device type is actually a different structure type,
  121. the device procedures must be declared as taking a gx_device * as their
  122. first argument, and must cast it to smurf_device * internally.  For
  123. example, in the code for the "memory" device, the first argument to all
  124. routines is called dev, but the routines actually use md to reference
  125. elements of the full structure, by virtue of the definition
  126.  
  127.     #define md ((gx_device_memory *)dev)
  128.  
  129. (This is a cheap version of "object-oriented" programming: in C++, for
  130. example, the cast would be unnecessary, and in fact the procedure table
  131. would be constructed by the compiler.)
  132.  
  133. Structure definition
  134. --------------------
  135.  
  136. This essentially duplicates the structure definition in gxdevice.h.
  137.  
  138. typedef struct gx_device_s {
  139.     int params_size;        /* size of this structure */
  140.     gx_device_procs *procs;        /* pointer to procedure structure */
  141.     char *name;            /* the device name */
  142.     int width;            /* width in pixels */
  143.     int height;            /* height in pixels */
  144.     float x_pixels_per_inch;    /* x density */
  145.     float y_pixels_per_inch;    /* y density */
  146.     gs_rect margin_inches;        /* margins around imageable area, */
  147.                     /* in inches */
  148.     gx_device_color_info color_info;    /* color information */
  149.     int is_open;            /* true if device has been opened */
  150. } gx_device;
  151.  
  152. The name in the structure should be the same as the name in devs.mak.
  153.  
  154. gx_device_common is a macro consisting of just the element definitions.
  155.  
  156. For sophisticated developers only
  157. ---------------------------------
  158.  
  159. If for any reason you need to change the definition of the basic device
  160. structure, or add procedures, you must change the following places:
  161.  
  162.     - This document and NEWS (if you want to keep the
  163.         documentation up to date).
  164.     - The definition of gx_device_common and/or the procedures
  165.         in gxdevice.h.
  166.     - The null device in gsdevice.c.  (Note that this device does
  167.         not allow procedure defaulting.)
  168.     - The tracing "device" in gstdev.c.  (Ditto.)
  169.     - The command list "device" in gxclist.c.  (Ditto.)
  170.     - The clip list accumulation and clipping "devices" in gxcpath.c.
  171.         (Ditto.)
  172.     - The "memory" devices in gdevmem.h and gdevmem*.c.  (Ditto.)
  173.     - The generic printer device macros in gdevprn.h.
  174.     - The generic printer device code in gdevprn.c.
  175.     - All the real devices in the standard Ghostscript distribution,
  176.         as listed in devs.mak.  (Most of the printer devices are
  177.         created with the macros in gdevprn.h, so you may not have to
  178.         edit the source code for them.)
  179.     - Any other drivers you have that aren't part of the standard
  180.         Ghostscript distribution.
  181.  
  182. You may also have to change the code for gx_default_get_props and/or
  183. gx_default_put_props (in gsdevice.c).  Note that if all you are doing
  184. is adding optional procedures, you do NOT have to modify any device
  185. drivers other than the ones specifically listed above; Ghostscript
  186. will substitute the default procedures properly.
  187.  
  188. ********
  189. ******** Coding conventions ********
  190. ********
  191.  
  192. While most drivers (especially printer drivers) follow a very similar
  193. template, there is one important coding convention that is not obvious
  194. from reading the code for existing drivers: Driver procedures must not use
  195. malloc to allocate any storage that stays around after the procedure
  196. returns.  Instead, they must use gs_malloc and gs_free, which have
  197. slightly different calling conventions.  (The prototypes for these are in
  198. gs.h, which is include